chrome.userScripts

תיאור

משתמשים ב-userScripts API כדי להריץ סקריפטים של משתמשים בהקשר של סקריפטים של משתמשים.

הרשאות

userScripts

כדי להשתמש ב-User Scripts API, chrome.userScripts, מוסיפים את ההרשאה "userScripts" לקובץ manifest.json ואת ההרשאה "host_permissions" לאתרים שבהם רוצים להריץ סקריפטים.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

זמינות

Chrome מגרסה 120 ואילך MV3 ואילך

מושגים ושימוש

סקריפט משתמש הוא קטע קוד שמוזן בדף אינטרנט כדי לשנות את המראה או ההתנהגות שלו. בניגוד לתכונות אחרות של התוסף, כמו סקריפטים של תוכן ו-chrome.scripting API, User Scripts API מאפשר להריץ קוד שרירותי. ה-API הזה נדרש לתוספים שמפעילים סקריפטים שהמשתמש סיפק ולא ניתן לשלוח אותם כחלק מחבילת התוסף.

הפעלת השימוש ב-userScripts API

אחרי שהתוסף מקבל הרשאה להשתמש ב-userScripts API, המשתמשים צריכים להפעיל מתג ספציפי כדי לאפשר לתוסף להשתמש ב-API. המתג הספציפי הנדרש וההתנהגות של ה-API כשהוא מושבת משתנים בהתאם לגרסה של Chrome.

אפשר להשתמש בבדיקות הבאות כדי לקבוע איזה מתג המשתמש צריך להפעיל, למשל במהלך תהליך ההצטרפות של משתמשים חדשים:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

בקטעים הבאים מתוארים המתגים השונים ואופן ההפעלה שלהם.

גרסאות Chrome שקדמו ל-138 (מתג מצב הפיתוח)

כמפתחי תוספים, כבר הפעלתם את מצב הפיתוח בהתקנה של Chrome. גם המשתמשים צריכים להפעיל את מצב הפיתוח.

אתם יכולים להעתיק ולהדביק את ההוראות הבאות במסמכי העזרה של התוסף למשתמשים

  1. כדי לעבור לדף התוספים, מזינים chrome://extensions בכרטיסייה חדשה. (כתוצאה מהתכנון, לא ניתן לקשר לכתובות URL מסוג chrome://).

  2. מפעילים את מצב הפיתוח בלחיצה על המתג לצד מצב פיתוח.

    דף התוספים של Chrome עם המתג של מצב הפיתוח מודגש

    דף התוספים (chrome://extensions)

גרסאות Chrome 138 ואילך (מתג אישור הסקריפטים של המשתמשים)

המתג Allow User Scripts מופיע בדף הפרטים של כל תוסף (לדוגמה, chrome://extensions/?id=YOUR_EXTENSION_ID).

אתם יכולים להעתיק ולהדביק את ההוראות הבאות במסמכי העזרה של התוסף למשתמשים:

  1. כדי לעבור לדף התוספים, מזינים chrome://extensions בכרטיסייה חדשה. (כתוצאה מהתכנון, לא ניתן לקשר לכתובות URL מסוג chrome://).
  2. לוחצים על הלחצן 'פרטים' בכרטיס התוסף כדי להציג מידע מפורט על התוסף.
  3. לוחצים על המתג לצד הרשאה לסקריפטים של משתמשים.
המתג 'אישור לסקריפטים של משתמשים' בדף הפרטים של התוסף
החלפת המצב של 'אישור לסקריפטים של משתמשים' (chrome://extensions/?id=abc...)

בדיקת זמינות ה-API

מומלץ לבצע את הבדיקה הבאה כדי לקבוע אם ממשק ה-API של userScripts מופעל, כי הוא פועל בכל הגרסאות של Chrome. הבדיקה הזו מנסה לבצע קריאה לשיטה chrome.userScripts(), שאמורה תמיד להצליח כשה-API זמין. אם הקריאה הזו מחזירה שגיאה, ה-API לא זמין:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

עבודה בעולמות מבודדים

גם סקריפטים של משתמשים וגם סקריפטים של תוכן יכולים לפעול בעולם מבודד או בעולם הראשי. עולם מבודד הוא סביבת הפעלה שלא נגישה לדף מארח או לתוספים אחרים. כך סקריפט של משתמש יכול לשנות את סביבת ה-JavaScript שלו בלי להשפיע על דף המארח או על סקריפטים של משתמשים ותוכן של תוספים אחרים. לעומת זאת, סקריפטים של משתמשים (וסקריפטי תוכן) לא גלויים לדף המארח או לסקריפטים של משתמשים ותוכן של תוספים אחרים. סקריפטים שפועלים בעולם הראשי זמינים לדפים המארחים ולתוספים אחרים, וגלויים לדפים המארחים ולתוספים אחרים. כדי לבחור את העולם, מעבירים את הערך "USER_SCRIPT" או "MAIN" בקריאה ל-userScripts.register().

כדי להגדיר מדיניות אבטחת תוכן לעולם USER_SCRIPT, צריך לבצע קריאה ל-userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

העברת הודעות

בדומה לסקריפטים של תוכן ולמסמכים מחוץ למסך, סקריפטים של משתמשים מתקשרים עם חלקים אחרים בתוסף באמצעות הודעות (כלומר, הם יכולים להפעיל את runtime.sendMessage() ואת runtime.connect() כמו כל חלק אחר בתוסף). עם זאת, הם מתקבלים באמצעות פונקציות ייעודיות לטיפול באירועים (כלומר, הן לא משתמשות ב-onMessage או ב-onConnect). הפונקציות האלה נקראות runtime.onUserScriptMessage ו-runtime.onUserScriptConnect. קל יותר לזהות הודעות מסקריפטים של משתמשים בעזרת בוררים ייעודיים, כי הם הקשר פחות מהימן.

לפני שליחת הודעה, צריך להפעיל את configureWorld() עם הארגומנט messaging שמוגדר כ-true. שימו לב שאפשר להעביר גם את הארגומנט csp וגם את הארגומנט messaging בו-זמנית.

chrome.userScripts.configureWorld({
  messaging: true
});

עדכוני תוספים

תסריטים של משתמשים נמחקים כשמתבצע עדכון של תוסף. אפשר להוסיף אותם חזרה על ידי הפעלת קוד בבורר האירועים runtime.onInstalled ב-service worker של התוסף. יש להשיב רק לסיבה "update" שהועברה ל-call back של האירוע.

דוגמה

הדוגמה הזו היא מהדוגמה של userScript במאגר הדוגמאות שלנו.

רישום סקריפט

בדוגמה הבאה מוצגת קריאה בסיסית ל-register(). הארגומנט הראשון הוא מערך של אובייקטים שמגדירים את הסקריפטים שרוצים לרשום. יש אפשרויות נוספות מלבד אלה שמוצגות כאן.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

סוגים

ExecutionWorld

העולם של JavaScript שבו סקריפט של משתמש מופעל.

טיפוסים בני מנייה (enum)

'MAIN'
מציינת את סביבת הביצוע של ה-DOM, שהיא סביבת הביצוע המשותפת עם JavaScript של דף המארח.

"USER_SCRIPT"
מציינת את סביבת הביצוע שספציפית לסקריפטים של משתמשים, והיא פטורה מ-CSP של הדף.

InjectionResult

גרסה 135 ואילך של Chrome

מאפיינים

  • documentId

    מחרוזת

    המסמך שמשויך להזרקה.

  • error

    מחרוזת אופציונלי

    השגיאה, אם יש כזו. הערכים error ו-result הם בלעדיים זה לזה.

  • frameId

    number

    המסגרת שמשויכת להזרקה.

  • תוצאה

    כל אופציונלי

    התוצאה של ביצוע הסקריפט.

InjectionTarget

גרסה 135 ואילך של Chrome

מאפיינים

  • allFrames

    boolean אופציונלי

    האם הסקריפט צריך להחדיר את עצמו לכל המסגרות בכרטיסייה. ברירת המחדל היא false. אסור שהערך הזה יהיה נכון אם צוין frameIds.

  • documentIds

    string[] אופציונלי

    המזהים של מזהי מסמכים ספציפיים שרוצים להחדיר. אסור להגדיר את הערך הזה אם הערך frameIds מוגדר.

  • frameIds

    number[] אופציונלי

    המזהים של הפריימים הספציפיים שרוצים להחדיר אליהם.

  • tabId

    number

    המזהה של הכרטיסייה שבה רוצים להחדיר את הקוד.

RegisteredUserScript

מאפיינים

  • allFrames

    boolean אופציונלי

    אם הערך הוא True, הקוד יוזרק לכל המסגרות, גם אם הפריים הוא לא הפריים העליון בכרטיסייה. כל מסגרת נבדקת בנפרד כדי לוודא שהיא עומדת בדרישות לגבי כתובות URL. אם היא לא עומדת בדרישות, היא לא תוזן למסגרות הצאצאים. ברירת המחדל היא false, כלומר מתבצע התאמה רק למסגרת העליונה.

  • excludeGlobs

    string[] אופציונלי

    תבניות של תווים כלליים לדפים שבהם סקריפט המשתמש הזה לא יוזרק.

  • excludeMatches

    string[] אופציונלי

    החרגת דפים שבהם סקריפט המשתמש הזה היה מוחדר אחרת. פרטים נוספים על התחביר של המחרוזות האלה מופיעים בקטע תבניות התאמה.

  • id [מזהה]

    מחרוזת

    המזהה של סקריפט המשתמש שצוין בקריאת ה-API. אסור שהמאפיין הזה יתחיל בתו '_' כי הוא שמור כקידומת למזהי סקריפט שנוצרו.

  • includeGlobs

    string[] אופציונלי

    תבניות של תווים כלליים לדפים שבהם סקריפט המשתמש הזה יוזרק.

  • js

    ScriptSource[] אופציונלי

    רשימת האובייקטים מסוג ScriptSource שמגדירים מקורות של סקריפטים שצריך להזריק לדפים תואמים. צריך לציין את המאפיין הזה עבור ${ref:register}, וכשהוא מצוין הוא חייב להיות מערך לא ריק.

  • תואם את:

    string[] אופציונלי

    קובע באילו דפים סקריפט המשתמש הזה יוזרק. פרטים נוספים על התחביר של המחרוזות האלה מופיעים בקטע תבניות התאמה. צריך לציין את המאפיין הזה עבור ${ref:register}.

  • runAt

    RunAt אופציונלי

    מציין מתי קבצי JavaScript מוחדרים לדף האינטרנט. הערך המועדף וערך ברירת המחדל הוא document_idle.

  • עולם

    ExecutionWorld אופציונלי

    סביבת ההפעלה של JavaScript שבה מריצים את הסקריפט. ברירת המחדל היא `USER_SCRIPT`.

  • worldId

    מחרוזת אופציונלי

    גרסה 133 ואילך של Chrome

    מזהה העולם שבו יתבצע הסקריפט של המשתמש. אם השדה הזה לא יצוין, הסקריפט יבוצע בעולם ברירת המחדל של סקריפט המשתמש. תקף רק אם השדה world מושמט או שהוא USER_SCRIPT. ערכים עם קו תחתון מוביל (_) שמורים.

ScriptSource

מאפיינים

  • קוד

    מחרוזת אופציונלי

    מחרוזת שמכילה את קוד ה-JavaScript שרוצים להחדיר. צריך לציין בדיוק אחד מהערכים file או code.

  • קובץ

    מחרוזת אופציונלי

    הנתיב של קובץ ה-JavaScript שרוצים להחדיר ביחס לתיקיית השורש של התוסף. צריך לציין בדיוק אחד מהערכים file או code.

UserScriptFilter

מאפיינים

  • ids

    string[] אופציונלי

    הפונקציה getScripts מחזירה רק סקריפטים עם המזהים שצוינו ברשימה הזו.

UserScriptInjection

גרסה 135 ואילך של Chrome

מאפיינים

  • injectImmediately

    boolean אופציונלי

    האם ההזרקה צריכה להתבצע ביעד בהקדם האפשרי. חשוב לזכור שזה לא מבטיח שההזרקה תתרחש לפני טעינת הדף, כי יכול להיות שהדף כבר נטען עד שהסקריפט מגיע ליעד.

  • רשימת האובייקטים מסוג ScriptSource שמגדירים מקורות של סקריפטים שרוצים להחדיר ליעד.

  • פרטים שמציינים את היעד שאליו רוצים להחדיר את הסקריפט.

  • עולם

    ExecutionWorld אופציונלי

    'העולם' של JavaScript שבו מריצים את הסקריפט. ברירת המחדל היא USER_SCRIPT.

  • worldId

    מחרוזת אופציונלי

    מזהה העולם שבו יתבצע הסקריפט של המשתמש. אם השדה הזה לא יצוין, הסקריפט יבוצע בעולם ברירת המחדל של סקריפט המשתמש. תקף רק אם השדה world מושמט או שהוא USER_SCRIPT. ערכים עם קו תחתון מוביל (_) שמורים.

WorldProperties

מאפיינים

  • csp

    מחרוזת אופציונלי

    מציין את ה-CSP של העולם. ברירת המחדל היא ה-CSP של העולם `ISOLATED`.

  • העברת הודעות

    boolean אופציונלי

    קובע אם ממשקי API של הודעות נחשפים. ברירת המחדל היא false.

  • worldId

    מחרוזת אופציונלי

    גרסה 133 ואילך של Chrome

    מזהה העולם הספציפי של סקריפט המשתמש שרוצים לעדכן. אם לא מציינים שם, המערכת מעדכנת את המאפיינים של העולם שמוגדר כברירת מחדל בסקריפט המשתמש. ערכים עם קו תחתון מוביל (_) שמורים.

Methods

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

הגדרת סביבת ההפעלה של `USER_SCRIPT`.

פרמטרים

  • נכסים

    WorldProperties

    מכיל את הגדרת העולם של סקריפט המשתמש.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

execute()

Promise Chrome מגרסה 135 ואילך 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

הוספה של סקריפט להקשר יעד. כברירת מחדל, הסקריפט ירוץ ב-document_idle, או באופן מיידי אם הדף כבר נטען. אם המאפיין injectImmediately מוגדר, ההזרקה של הסקריפט תתבצע בלי המתנה, גם אם הטעינה של הדף לא הסתיימה. אם הסקריפט מקבל ערך של הבטחה, הדפדפן ימתין עד שההבטחה תתבצע ויחזיר את הערך שנוצר.

פרמטרים

החזרות

  • Promise<InjectionResult[]>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

הפונקציה מחזירה את כל סקריפטים של משתמשים שנרשמו באופן דינמי עבור התוסף הזה.

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

    אם מציינים את השם, השיטה הזו מחזירה רק את סקריפטים של המשתמשים שתואמים לו.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (scripts: RegisteredUserScript[]) => void

החזרות

  • יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

getWorldConfigurations()

Promise Chrome מגרסה 133 ואילך 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

אחזור של כל הגדרות העולם הרשומים.

פרמטרים

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (worlds: WorldProperties[]) => void

החזרות

  • Promise<WorldProperties[]>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

הרשמה של סקריפט משתמש אחד או יותר לתוסף הזה.

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

    מכיל רשימה של סקריפטים של משתמשים שרוצים לרשום.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

resetWorldConfiguration()

Promise Chrome מגרסה 133 ואילך 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

איפוס ההגדרות של עולם של סקריפט משתמש. כל סקריפט שמחדיר לעולם עם המזהה שצוין ישתמש בהגדרת ברירת המחדל של העולם.

פרמטרים

  • worldId

    מחרוזת אופציונלי

    המזהה של עולם הסקריפט של המשתמש שרוצים לאפס. אם לא יצוין, תתבצע איפוס של הגדרות ברירת המחדל של העולם.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

ביטול הרישום של כל סקריפט המשתמש שרשום באופן דינמי עבור התוסף הזה.

פרמטרים

  • סינון

    UserScriptFilter אופציונלי

    אם יצוין, השיטה הזו תבטל את הרישום של סקריפטים של משתמשים שתואמים לו בלבד.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

עדכון של סקריפט משתמש אחד או יותר של התוסף הזה.

פרמטרים

  • סקריפטים

    RegisteredUserScript[]

    מכיל רשימה של סקריפטים של משתמשים שצריך לעדכן. נכס מתעדכן בסקריפט הקיים רק אם הוא צוין באובייקט הזה. אם יש שגיאות במהלך ניתוח הסקריפט או אימות הקובץ, או אם המזהים שצוינו לא תואמים לסקריפט שרשום במלואו, לא מתבצע עדכון של סקריפטים.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ה-promise ייפתר עם אותו סוג שמוענק ל-callback.